home *** CD-ROM | disk | FTP | other *** search
/ CD Ware Multimedia 1995 May / cd Ware (Juegos) Epimundo.iso / DOS / C / BITSTR.ZIP / BITSTR.DOC < prev   
Encoding:
Text File  |  1990-11-25  |  8.0 KB  |  163 lines
  1.          bitstr.doc: documentation for the "bitstr" (v1.20) C routines
  2.  
  3.      This is the second release of the "bitstring" routines.
  4.      The routines included in this .ZIP file are intended to replace the 
  5. previous release of the same routines in the file bitstr.arc. These C routines 
  6. arose from an article on pages 34-43 of the April, 1989 issue of Computer 
  7. Language Magazine. I thought the routines given there were somewhat 
  8. inefficient, and so I took the idea and rewrote the functions into much 
  9. simpler (and, perhaps, less portable) versions. 
  10.      The idea behind the routines is to implement, in C, a way to store a 
  11. true, numberable array of "boolean" values, without using entire characters or 
  12. even bitfields (whose values must be individually named-- not usable in an 
  13. indexed-array fashion). The array is made up of unsigned ints; the int is, on 
  14. the 8086, 8088, and the 80286 and 80386 in real mode, the same width in bits 
  15. (16) as the chip's data bus, making bitstring bit shifting operations 
  16. operate more quickly. Each bit in an unsigned int can become one boolean 
  17. value. Therefore, one unsigned int can store sixteen bitstring values. 
  18.      Unlike the last version (1.10) of these routines, there are now two ways 
  19. to use the functions: as true, linkable functions, or as preprocessor 
  20. replacements using #define statements in a single header file. The primary 
  21. difference between the two is that the macro versions are good for use when 
  22. speed, not size, is of utmost importance: No function-calling overhead is 
  23. incurred, but replacing the macro at more than a few locations is very 
  24. space-consuming. On the other hand, the function versions are slightly 
  25. slower, but a function call uses less space than the macro expansion.
  26. In general, for small (one-file) projects I use the macro versions, and for 
  27. large programs I link in the functions.
  28.      There are three bitstring routines (their prototypes are also shown):
  29.  
  30.      void clear_bit(unsigned int *bitstr, int bit)
  31.        This routine clears to false or 0 a bit in a bitstring. The "bitstr"
  32.        parameter is a pointer to the bitstring array of unsigned ints. The 
  33.        "bit" parameter specifies the bit to be operated upon.
  34.  
  35.      void set_bit(unsigned int *bitstr, int bit)
  36.        The parameters for this routine are the same as for clear_bit(), except 
  37.        that the "bit" bit in the "bitstr" array is set to true or 1.
  38.  
  39.      int test_bit(unsigned int *bitstr, int bit)
  40.        The parameters here are the same as before. test_bit() returns an 
  41.        integer that is zero if the "bit" bit is clear/false/0, and non-zero if 
  42.        "bit" is set/true/1.
  43.  
  44.      Note that the routines use a "bit" parameter that starts counting at 0, 
  45. not 1.
  46.      The bitstring routines are designed to work with pointers to one or more 
  47. unsigned ints. This makes it possible to use more than 16 values in one array 
  48. by declaring an array of unsigned ints, and passing the address of the first 
  49. one as the first parameter in calls to these routines. The routines 
  50. automatically choose the proper unsigned int to work on based on the value of 
  51. the "bit" parameter-- if the value is over 15, modulo division is used to 
  52. bring it to a value between 0 and 15, and the position in memory is 
  53. incremented accordingly. 
  54.      Example:
  55.  
  56.  
  57. #include <stdio.h>
  58. #include "bitstr_h.h"  /* or bitstr_f.h and link-in bitstr_f.c */
  59.  
  60. unsigned int  data[2];  /* allows use of up to 32 values */
  61.  
  62. void main(void)
  63. {
  64.   register int  i;
  65.  
  66.   for (i=0; i<22; i++) set_bit(&data[0],i);  /* pass address of int array */
  67.   for (i=0; i<32; i++) if (test_bit(&data[0],i)) printf("bit %d is set\n",i);
  68.   for (i=0; i<22; i++) clear_bit(&data[0],i);
  69. }
  70.  
  71.  
  72. Here are descriptions of the files included in this release:
  73.  
  74.      bitstr.doc: What else could you be looking at?
  75.  
  76.      bitstr_f.h, bitstr_f.c: These two files are to be used just as in version 
  77. 1.10, i.e. compile bitstr_f.c under any needed memory model, then #include 
  78. "bitstr_f.h" in your source code, and link the compiled bitstr_f.obj with your 
  79. executable program.
  80.  
  81.      bitstr_h.h: This is the alternate way of using the bitstring routines:
  82. All you need to do here is to #include "bitstr_h.h" in any source files that 
  83. use the bitstring routines, then just leave it-- there is no need to compile 
  84. and link bitstr_f.c, as the routines are replaced in your source by the C 
  85. preprocessor. You should not include both bitstr_f.h and bitstr_h.h at the 
  86. same time: Use either the #include "bitstr_h.h" method, or the #include 
  87. "bitstr_f.h", compile-and-link bitstr_f.c, method, but not both.
  88.  
  89.      In the files, the macro US is #defined to be 16, the width in bits of the 
  90. CPU. This will work for 8086, 8088, and 80286 applications (as well as the 
  91. 80386 in real mode). Another macro, HEX1, is #defined to be (unsigned) 
  92. 0x0001. This macro represents a single set bit at the rightmost position of 
  93. the integer, and is used in the routines to allow a single bit to be shifted 
  94. around and logically ANDed or ORed. 
  95.      
  96.      I have strived to make these routines as bug-free as possible, and they 
  97. have worked well in several programming projects. However, if you do find an 
  98. error (or just want to make comments, etc.), I can be contacted: 
  99.  
  100.      Erik Mavrinac
  101.      CIS [73507,3523]
  102.  
  103. Please note that the address in bitstr.arc 1.10 is no longer valid: I prefer 
  104. electronic mail, because I am moving frequently now to and from college.
  105.  
  106. revision history:
  107.   v1.00: The original routines emerged.
  108.   v1.10: Fixes for errors in the entire concept as implemented in v1.00.
  109.          Also, original documentation file written and bundled for upload to 
  110.          CIS.
  111.   v1.20: What you have here. The single lines of the original functions began 
  112.          to appear simple enough to put into macros. Also, documentation 
  113.          changes were made.
  114.  
  115.  
  116.  
  117.          ----------------end-of-author's-documentation---------------
  118.  
  119.                          Software Library Information:
  120.  
  121.                     This disk copy provided as a service of
  122.  
  123.                            Public (software) Library
  124.  
  125.          We are not the authors of this program, nor are we associated
  126.          with the author in any way other than as a distributor of the
  127.          program in accordance with the author's terms of distribution.
  128.  
  129.          Please direct shareware payments and specific questions about
  130.          this program to the author of the program, whose name appears
  131.          elsewhere in  this documentation. If you have trouble getting
  132.          in touch with the author,  we will do whatever we can to help
  133.          you with your questions. All programs have been tested and do
  134.          run.  To report problems,  please use the form that is in the
  135.          file PROBLEM.DOC on many of our disks or in other written for-
  136.          mat with screen printouts, if possible.  PsL cannot debug pro-
  137.          programs over the telephone, though we can answer questions.
  138.  
  139.          Disks in the PsL are updated  monthly,  so if you did not get
  140.          this disk directly from the PsL, you should be aware that the
  141.          files in this set may no longer be the current versions. Also,
  142.          if you got this disk from another vendor and are having prob-
  143.          lems,  be aware that  some files may have become corrupted or
  144.          lost by that vendor. Get a current, working disk from PsL.
  145.  
  146.          For a copy of the latest monthly software library newsletter
  147.          and a list of the 2,000+ disks in the library, call or write
  148.  
  149.                            Public (software) Library
  150.                                P.O.Box 35705 - F
  151.                             Houston, TX 77235-5705
  152.  
  153.                                 1-800-2424-PSL
  154.                              MC/Visa/AmEx/Discover
  155.  
  156.                           Outside of U.S. or in Texas
  157.                           or for general information,
  158.                               Call 1-713-524-6394
  159.  
  160.                           PsL also has an outstanding
  161.                           catalog for the Macintosh.
  162.  
  163.